Node / meshtastic / Meshtastic-Android / files / docs / decisions / navigation3-api-alignment-2026-03.md

Displaying Rendered • View raw • Download

<!--

• Copyright (c) 2026 Meshtastic LLC

-

• This program is free software: you can redistribute it and/or modify

• it under the terms of the GNU General Public License as published by

• the Free Software Foundation, either version 3 of the License, or

• (at your option) any later version.

-->

Date: 2026-03-26

Status: Active

Scope: Adoption of Navigation 3 T3838381.1.0-beta01 Scene APIs, transition metadata, ViewModel scoping, and Material 3 Adaptive integration.

Supersedes: navigation3-parity-2026-03.md Alpha04 Changelog section (versions updated).

Key finding: The T383838ViewModelStoreNavEntryDecorator is available and provides automatic per-entry ViewModel scoping tied to backstack lifetime. The project passes it as an T383838entryDecorator to T383838NavDisplay via T383838MeshtasticNavDisplay in T383838core:ui/commonMain.

ViewModels obtained via T383838koinViewModel() inside T383838entry<T> blocks are scoped to the entry's backstack lifetime and automatically cleared when the entry is popped.

Key finding: The JetBrains T383838adaptive-navigation3 artifact at T3838381.3.0-alpha06 includes T383838ListDetailSceneStrategy and T383838SupportingPaneSceneStrategy. The project uses both via T383838rememberListDetailSceneStrategy and T383838rememberSupportingPaneSceneStrategy in T383838MeshtasticNavDisplay, with draggable pane dividers via T383838VerticalDragHandle + T383838paneExpansionDraggable.

This means the project successfully uses the M3 Adaptive Scene bridge through T383838NavDisplay(sceneStrategies = ...). Feature entries annotate themselves with T383838ListDetailSceneStrategy.listPane(), T383838.detailPane(), or T383838.extraPane() metadata.

When to revisit: Monitor the JetBrains adaptive fork for T383838MaterialListDetailSceneStrategy inclusion. It will likely arrive when the JetBrains fork catches up to the AndroidX T3838381.3.0-alpha09+ feature set.

Status: ✅ Adopted (2026-03-26). T383838MeshtasticNavigationSuite now uses T383838NavigationSuiteScaffold with T383838calculateFromAdaptiveInfo() and custom T383838NavigationSuiteType coercion. No further alignment needed.

Status: ✅ Adopted (2026-03-26). Each backstack entry now gets its own T383838ViewModelStoreOwner via T383838rememberViewModelStoreNavEntryDecorator(). ViewModels obtained via T383838koinViewModel() are automatically cleared when their entry is popped. Encapsulated in T383838MeshtasticNavDisplay in T383838core:ui/commonMain.

Impact: Fixes subtle ViewModel leaks where popped entries retain their ViewModel in the Activity/Window store. Eliminates the need for manual T383838key = "metrics-$destNum" ViewModel keying patterns over time.

Status: ✅ Adopted (2026-03-26). A shared 350 ms crossfade (T383838fadeIn + T383838fadeOut) is applied for both forward and pop navigation via T383838MeshtasticNavDisplay. This replaces the library's platform defaults (Android: 700 ms fade; Desktop: no animation) with a faster, consistent transition.

Impact: Immediate UX improvement on both Android and Desktop. Desktop now has visible navigation transitions.

Status: ✅ Adopted (2026-03-26). T383838MeshtasticNavDisplay includes T383838DialogSceneStrategy in T383838sceneStrategies before T383838SinglePaneSceneStrategy. Feature modules can now use T383838entry<T>(metadata = DialogSceneStrategy.dialog()) { ... } to render entries as overlay Dialogs with proper backstack lifecycle and predictive-back support.

Impact: Cleaner dialog lifecycle management available for future dialog routes. Existing dialogs via T383838AlertHost are unaffected.

Status: ✅ Adopted (2026-03-26). A new T383838MeshtasticNavDisplay composable in T383838core:ui/commonMain encapsulates the standard T383838NavDisplay configuration:

• Entry decorators: T383838rememberSaveableStateHolderNavEntryDecorator + T383838rememberViewModelStoreNavEntryDecorator

• Scene strategies: T383838DialogSceneStrategy + T383838SinglePaneSceneStrategy

• Transition specs: 350 ms crossfade (forward + pop)

Both T383838app/Main.kt and T383838desktop/DesktopMainScreen.kt now call T383838MeshtasticNavDisplay instead of configuring T383838NavDisplay directly. The T383838lifecycle-viewmodel-navigation3 dependency was moved from host modules to T383838core:ui.

Individual entries can declare custom transitions via T383838entry<T>(metadata = NavDisplay.transitionSpec { ... }). This is most useful when different route types should animate differently (e.g., detail screens slide in, settings screens fade).

Impact: Polish improvement. Low priority until default transitions (P1) are established. Now unblocked by P1 adoption.

The T383838ListDetailSceneStrategy and T383838SupportingPaneSceneStrategy are adopted and working. Consider writing additional custom T383838SceneStrategy implementations for specialized layouts (e.g., three-pane "Power User" scenes) as the Navigation 3 Scene API matures.

~~Adopt P0 (ViewModel scoping) and P1 (default transitions) now. Defer P2/P3 and Scene-based multi-pane until the JetBrains adaptive fork adds T383838MaterialListDetailSceneStrategy.~~

Updated 2026-03-26: P0, P1, and P2 adopted and consolidated into T383838MeshtasticNavDisplay in T383838core:ui/commonMain. P3 (per-entry transitions) is available for incremental adoption by feature modules. Scene-based multi-pane remains deferred.

• Navigation 3 source: T383838navigation3-ui T3838381.1.0-beta01 (inspected from Gradle cache)

• NavDisplay.kt (upstream)

• SceneStrategy.kt (upstream)

• Material 3 Adaptive JetBrains fork: T383838org.jetbrains.compose.material3.adaptive T3838381.3.0-alpha06